<!DOCTYPE html>
<html>
<head>
    <title>A Paginated JQuery UI Autocomplete Widget</title>
	<style type="text/css">
	
		div.scottsJewels
		{
	
		}	
			div.scottsJewels h1 
			{
				font-size: 28px;
			}
	
			div.scottsJewels h2 
			{
				text-transform: none;
				font-size: 24px;
				border-bottom: 1px solid #CCCCCC;		
			}

			div.scottsJewels h3 
			{
				font-size: 20px;
				border-bottom: 1px solid #CCCCCC;
			}
		
			div.scottsJewels h4 
			{
				font-size: 16px;		
				text-decoration:underline;
			}			
			
			div.scottsJewels h5 
			{
				font-size: 16px;		
				
			}					
				
			div.scottsJewels a img.smallImage
			{							
				border: none;
				border:0px; 
				display: block; 
				margin-left: auto; 
				margin-right: auto								
			}
			
			div.scottsJewels p.smallImageDescription
			{
				font-size: 12px;
				font-style: italic;
				position: relative;
				bottom: 10px;
				text-align: center;
			}
		
			div.scottsJewels pre.codeSample 
			{
				color: #000080;		
				background-color: #F5FFFA;
				font-size:12px;
				max-width:800px;
				overflow-x:auto;	
				overflow-y:hidden;	
				border-bottom: 1px solid #CCCCCC;
				border-top: 1px solid #CCCCCC;
				border-left: 1px solid #CCCCCC;
				border-right: 1px solid #CCCCCC;
				word-wrap: normal;
			}
			
			div.scottsJewels .inlineCode			
			{			
				color: #000080;				
			}			
		
			div.scottsJewels .codeSampleReference 
			{
				font-size: 12px;
				font-style: italic;
				position: relative;
				bottom: 10px;
			}

				@-moz-document url-prefix() 
				{				
					div.scottsJewels table
					{			
						border: none;
					}		
				}	
          
          div.scottsJewels div.addendum
          {
            padding:10px;
            border: 1px solid #9f6000;
            color: #9f6000;
            background-color: #feefb3;
            font-style: italic; 
          }													
	</style>	
</head>
<body>
	<div class="scottsJewels">
	
		<p>The <a target="_blank" href="http://jqueryui.com/autocomplete/">JQuery UI Autocomplete Widget</a> allows you to return a list of suggestions based upon a query string. The widget works great unless the user does not know what to search for. For example, if the user wants to search through a large database of people using only a single letter (presumably the first letter of the last name) the Autocomplete Widget quickly becomes unwieldy. Either the suggestions need to be truncated or the list of suggestions becomes so large as to be unusable.</p> 

		<p>To resolve this problem I have extended the JQuery UI Autocomplete Widget and added pagination. Arrows allow the user to cycle through pages of suggestions. Each page of is retrieved using AJAX. Click <a target="_blank" href="http://jsfiddle.net/ke3zK/3/">here</a> for a jsFiddle sample. The sample uses <a target="_blank" href="https://github.com/appendto/jquery-mockjax">MockJax</a> to simulate the AJAX calls. A complete end-to-end example using ASP.NET MVC is available <a target="_blank" href="http://scotts-jewels.googlecode.com/svn/APaginatedJQueryUIAutocompleteWidget/PaginatedAutocomplete.zip">here</a>.</p>

		<p>The Paginated Autocomplete Widget inherits the same <a target="_blank" href="http://api.jqueryui.com/autocomplete/">API</a> as the Autocomplete Widget from which it is derived. However, there are some differences to be aware of ...</p>

		<p>First, the web server endpoint that handles the AJAX GET must support three parameters - search, pageSize, and pageIndex. <strong>search</strong> is the query string provided by the user. <strong>pageSize</strong> is the number of items to return per page. <strong>pageIndex</strong> is the page to return.</p>

		<pre class="codeSample csharp"><code>	
[HttpGet]
public JsonResult SearchCars(string search, int pageSize=20, int pageIndex=0)
{
   // Your logic here.
}</code>
		</pre>
		<span class="codeSampleReference">ASP.NET MVC Controller ActionMethod to support the Paginated Autocomplete Widget.</span>	

		<p>Second, the Paginated Autocomplete expects a JSON response from the web server in a specific format. The Widget requires this format to facilitate  pagination. <strong>data</strong> is an array of text/value objects that will get bound to to the list of suggestions. <strong>total</strong> is the total number of unpaginated suggestions that the search query returned.</p>

		<pre class="codeSample javascript"><code>			
{	
   data : [
      { text : "Item 1", value : 0 },
      { text : "Item 2", value : 1 },
      { text : "Item 3", value : 2 }
   ],
   total : 1000
}</code>
		</pre>
		<span class="codeSampleReference">JSON result expected by the Paginated Autocomplete Widget.</span>	
		
		<p>Third, when using the Paginated Autocomplete Widget in Javascript you need to specify <strong>sourceUrl</strong>. The Widget will automatically generate an AJAX GET to the sourceUrl and retrieve paginated suggestions as necessary. This is different than the Autocomplete Widget where you need to define the <a target="_blank" href="http://api.jqueryui.com/autocomplete/#option-source">source</a> method as well as the underlying AJAX GET. The obfuscation is necessary to facilitate pagination. In addition <strong>pageSize</strong> is an optional parameter that determines the number of suggestions per page.</p> 
		<pre class="codeSample javascript"><code>	
&lt;input id="myFilter" type="text" /&gt;   	      
	
&lt;script type="text/javascript"&gt;

   $(document).ready(function() {	
	
      $("#myFilter").paginatedAutocomplete({
         pageSize: 10,
         sourceUrl: '/Simpsons/SearchCharacters'
      });
   }); 

&lt;/script&gt;</code>
		</pre>
		<span class="codeSampleReference">Using the Paginated Autocomplete Widget in Javascript.</span>

		<p>The Paginated Autocomplete Widget requires <a target="_blank" href="http://code.jquery.com/jquery-1.9.1.js">JQuery 1.9.1</a> or newer and <a target="_blank" href="http://code.jquery.com/ui/1.10.3/jquery-ui.js">JQuery UI 1.10.3</a> or newer. I have tested it against Internet Explorer 7/8/9/10, Firefox 21, and Chrome 27. It will probably run in other permutations as well. Please let me know if you have any comments or questions.</p>	
	</div>	
</body>
</html>



